home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff290.lzh / IPC / Docs / Standard Flags < prev    next >
Text File  |  1989-12-11  |  10KB  |  226 lines
  1.                 IPC Message and Item Standard Flags
  2.                 ===================================
  3.  
  4.                           -- May 1989 --
  5.  
  6.  
  7. Each IPCMessage, and each IPCItem contained within it, has a 32-bit Flags
  8. field used by Client and Server to inform their counterpart process of
  9. various requirements and occurrences.  The upper sixteen bits of the
  10. longword are reserved for system-wide flags, and the lower sixteen are
  11. available for designer-specified uses associated with particular message
  12. IDs.
  13.  
  14. Typical of the sort of thing that must be signalled: a message item may
  15. refer to a block of data created by the original client, and the Server
  16. must know whether it can assume responsiblity for this data (disposing
  17. of it when done) or whether the Client wants it back with the reply.
  18. (This is distinct from who can change the data in the block.  In general,
  19. data can be changed by whichever process "owns" the associated message
  20. at the time; in other words the server -- and only the server -- can
  21. write to a data block passed to it in a message UNTIL it replies the
  22. message; from that point on the server must NOT touch it, or even assume
  23. it still exists.)
  24.  
  25. If a Server does not recognize the message ID, or cannot handle an Item,
  26. it has to report this in the reply, so flags are reserved for this.
  27. Depending on other bits, not handling an item may or may not be fatal to
  28. handling the message as a whole, and the server should respond suitably.
  29.  
  30. Each flag bit has the same meaning -- or as close as possible to it --
  31. for both ipc_Flags (Message) and ii_Flags (Item) usage; most of the flags
  32. are suitable for both.  Some of them will usually be set by the client and
  33. interpreted by the server; others may work in either direction.  In most
  34. cases only a subset of the flags will be needed for a particular Server.
  35.  
  36. The remainder of this document describes the actual system flags currently
  37. assigned.  Refer to IPC.h for the actual bit assignments.  The reader must
  38. realize that at this stage some of these flags have not yet seen actual
  39. use, and there are undoubtedly hazy regions, even outright fatal omissions.
  40. Please resist the temptation to use any of the assigned bits for other than
  41. the exactly specified purpose.  If you need another flag, use one of the
  42. lower sixteen bits if possible; if you think it should be a system flag
  43. please contact the author so that it can be added to the set (but remember
  44. that there are currently only six free spaces!).  And do the same of course
  45. if you notice any other horrors or necessary features.
  46.  
  47.  
  48.  
  49. Flags normally set only by Client:
  50. ---------------------------------
  51.  
  52. IPC_TRANSFER
  53.  
  54.     in Item:
  55.        Ownership of this Data block may be transferred to receiver.
  56.        If set by Client, the Server may or may NOT choose to assume
  57.        responsibility for the block.  If it does take it over, it MUST
  58.        clear ii_Ptr AND this bit before reply.  If it does not take it
  59.        over, it should leave the bit set, so the Client will know it has to
  60.        dispose of the data.  The Server does NOT have to set this bit if
  61.        the Client never set it, of course; unless this bit was initially
  62.        set -- or IPC_SERVER_OWNED is a possibility -- the client will
  63.        assume it owns ALL data in a returned message.
  64.  
  65.        (In certain situations -- which would have to be specified in the
  66.        definition of the Message/Item IDs -- there are some other possible
  67.        responses to this flag.  It might be specified that the Server could
  68.        REPLACE the pointer before replying -- disposing of the old data and
  69.        supplying new.  Here the IPC_MODIFIED bit would need to be used.
  70.        Alternatively, the Server might just possibly set the
  71.        IPC_SERVER_OWNED bit and return the pointer unchanged, though this
  72.        option is really intended for other things; it could only apply
  73.        where the Client needs to access the block, but will return it once
  74.        again to the Server at a later time.)
  75.  
  76.     in Message:
  77.        Ownership of all Items in the message may be transferred.
  78.        May be used where appropriate instead of flagging all the Items
  79.        individually; the server should then accept either all the items or
  80.        none (clearing or retaining this bit, but nulling all the individual
  81.        ii_Ptrs if it takes them over).
  82.        In particular, this flag should ALWAYS be set in those cases where
  83.        no ReplyPort is supplied.  (It is standard practice for a Server
  84.        to reply a message, but there are oocasions where, for instance,
  85.        the Client may not be able to remain around for a reply.  To prevent
  86.        catastrophe, such situations must be clearly flagged!)  In this
  87.        situation, the Server has no choice but to accept responsibility,
  88.        so the user must be very sure it is capable of this before he sends
  89.        it such a message.
  90.  
  91.  
  92. IPC_NETWORK
  93.  
  94.     in Item or Message:
  95.        The data in this block or message may be transmitted to another
  96.        machine.  In other words the data referenced is meaningful outside
  97.        the current machine environment.  It may be anything from a text
  98.        block to a bit image, but it is NOT a file handle, message port,
  99.        or other internal-use-only object.
  100.  
  101.  
  102. IPC_INMESSAGE
  103.  
  104.     in Item:
  105.        The data block referenced by this Item is included in the message
  106.        block itself, in a user data area specified when CreateIPCMsg() was
  107.        called.  This is only really useful for a message with no ReplyPort,
  108.        so the Server will know not to delete this block twice; if the
  109.        message IS replied, the Server will not be able to take the block
  110.        over anyway (because it is within the replied structure), so the
  111.        flag is superfluous and need not be set -- just don't set
  112.        IPC_TRANSFER.
  113.  
  114.     in Message:
  115.        As for Item, but referring to all Items.
  116.        A situation where this flag would be appropriate is where one
  117.        message Item's contents is itself an IPCMessage structure (as a
  118.        template for generating other messages, say); setting the flag in
  119.        this SECONDARY structure's ipc_Flags would indicate to the Server
  120.        that it could safely duplicate -- and possibly modify -- the
  121.        original.
  122.  
  123.  
  124. IPC_NONSTANDARD
  125.  
  126.     in Item or Message:
  127.        The data in this block or message does NOT conform to the standard
  128.        pointer-to-single-data-block protocol (it might be a list structure,
  129.        for instance).  The Server must NOT delete or modify this UNLESS it
  130.        knows how to handle it.  NOTE: ANY ID used with this flag MUST have
  131.        common meaning to ALL programs (if they recognize it); in other
  132.        words, if you design a message that needs it, make sure that the
  133.        IDs you use are unique, and get them disseminated as fast as
  134.        possible so that they don't get used for something else.
  135.  
  136.  
  137. IPC_VITAL
  138.  
  139.     in Item:
  140.        This Item ID MUST be recognized, otherwise the whole message must
  141.        be replied unprocessed (with IPC_REJECT set).  Servers should be
  142.        prepared to look for this bit BEFORE they do anything irreversible
  143.        to any Item they do recognize.
  144.  
  145.     in Message:
  146.        All Items in the message must be understood by the Server.
  147.  
  148.  
  149.  
  150. Flags normally set only by server on reply:
  151. ------------------------------------------
  152.  
  153. IPC_REJECT
  154.        (this bit was originally designated IPC_NOTKNOWN, but the current
  155.         name seems better suited.  The old definition is still in IPC.h
  156.         but should not be used in new programs.)
  157.  
  158.     in Item:
  159.        The server could not handle this Item either because it did not
  160.        understand the ID or because it was unable to process it.  If it
  161.        did recognize the ID but for some reason failed in its assignment,
  162.        it should also set IPC_FAILED.  (Note that IPC_REJECT is specifically
  163.        assigned to the sign bit of the Flags longword, to allow quick
  164.        checking if desired, so it should always be set in ADDITION to
  165.        IPC_FAILED.)
  166.  
  167.     in Message:
  168.        Either the Message ID itself was not recognized, or some problem
  169.        occurred while processing Items that was judged fatal (possibly
  170.        IPC_VITAL was encountered on an unrecognized item, or an expected
  171.        Item was not found).  If a particular Item caused the problem,
  172.        the IPC_CHECKITEM bit should be set as well, and the appropriate
  173.        flags (including IPC_REJECT) set in the offending Item.  IPC_FAILED
  174.        can of course also be used if relevant.
  175.  
  176.  
  177. IPC_FAILED
  178.  
  179.     in Item or Message:
  180.        The IPC_REJECT flag was set because the Server failed to handle an
  181.        ID that it is designed to (rather than just not recognizing the
  182.        block).  Useful only as secondary information to the Client; in
  183.        some cases it might be helpful to assign some of the user definable
  184.        bits as indications of more specific reasons.
  185.  
  186.  
  187. IPC_MODIFIED
  188.  
  189.     in Item:
  190.        The server modified the data, either within the supplied data block
  191.        or -- if permitted -- by replacing the block pointer.  Changing the
  192.        pointer is only permitted if a) this particular Item ID is defined
  193.        to allow it, and b) if IPC_TRANSFER is set; on reply both
  194.        IPC_TRANSFER and IPC_MODIFIED should be set.
  195.        This flag should also be used (for consistency at least) where
  196.        the Item from the Client had a null pointer field that is filled
  197.        in by the server with a created data block; it might be combined
  198.        with other relevant bits (IPC_SERVER_OWNED in particular).
  199.  
  200.     in Message:
  201.        Usefulness unclear -- one of those hazy areas...
  202.  
  203.  
  204. IPC_SERVER_OWNED
  205.  
  206.     in Item only:
  207.        The server owns this data Item.  Normally it will have created it,
  208.        and for some reason is not able to pass ownership to the Client --
  209.        usually because it or other processes are sharing it.  The Client
  210.        MUST at some later point send the Item back (in another message)
  211.        with both IPC_SERVER_OWNED and IPC_TRANSFER set, to indicate that
  212.        it has finished with it; the Server will of course then null ii_PTR
  213.        and clear the bits in the reply.
  214.  
  215.  
  216. IPC_CHECKITEM
  217.  
  218.     in Message only:
  219.        Associated with IPC_REJECT -- which must be set also -- to indicate
  220.        that one or more particular items caused the message to be rejected.
  221.        Appropriate flags should be set in these items as well.
  222.  
  223.  
  224.                               % % % % % %
  225.  
  226.